{smcl}
{* 27aug2002}{...}
{hline}
help for {hi:survwgt}
{hline}

{title:Survey sampling weights: adjustment and replicate weight creation}

{p 4 25}{cmd:survwgt} {cmdab:cr:eate}{space 7}{it:weight_type} {cmd:,}
		{cmdab:str:ata(}{it:varname}{cmd:)} {cmdab:psu(}{it:varname}{cmd:)}
		{cmdab:w:eight(}{it:varname}{cmd:)} {cmdab:stem(}{it:stem}{cmd:)}
		[ {cmd:fay(}{it:#}{cmd:)} {cmd:dof(}{it:#}{cmd:)}
		{cmdab:hadm:at(}{it:matname}{cmd:)} {cmdab:hadf:ile(}{it:matrix_file_name}{cmd:)}
		{cmdab:nod:ots} ]

{p 25 25}{it:weight_type} is one of

{p 25 30}{cmd:brr} - balanced repeated replication weights{p_end}
{p 25 30}{cmd:jk1} - unstratified delete-one jackknife weights{p_end}
{p 25 30}{cmd:jk2} - two per stratum delete-one jackknife weights{p_end}
{p 25 30}{cmd:jkn} - delete-n jackknife weights{p_end}

{p 4 25}{cmd:survwgt} {cmdab:post:stratify}{space 1}{it:varspec} {cmd:,}
		{cmdab:by(}{it:varlist}{cmd:)} {cmdab:t:otvar(}{it:varname}{cmd:)}
		{ {cmdab:g:enerate(}{it:varlist}{cmd:)} | {cmdab:stem(}{it:stem}{cmd:)} |
		{cmdab:pre:fix(}{it:prefix}{cmd:)} | {cmd:replace} | {cmd:modify} }

{p 4 25}{cmd:survwgt} {cmdab:rake}{space 9}{it:varspec} {cmd:,}
		{cmdab:by(}{it:varlist}{cmd:)} {cmdab:t:otvars(}{it:varlist}{cmd:)}
		{ {cmdab:g:enerate(}{it:varlist}{cmd:)} | {cmdab:stem(}{it:stem}{cmd:)} |
		{cmdab:pre:fix(}{it:prefix}{cmd:)} | {cmd:replace} | {cmd:modify} }

{p 4 25}{cmd:survwgt} {cmdab:nonr:esponse}{space 2}{it:varspec} {cmd:,}
		{cmdab:by(}{it:varlist}{cmd:)} {cmdab:r:espvar(}{it:varname}{cmd:)}
		{ {cmdab:g:enerate(}{it:varlist}{cmd:)} | {cmdab:stem(}{it:stem}{cmd:)} |
		{cmdab:pre:fix(}{it:prefix}{cmd:)} | {cmd:replace} }

{p 25 25}{it:varspec} is one of

{p 25 30}{it:varlist} - a Stata variable list{p_end}
{p 25 30}{cmd:[pw]}   - indicates the full sample weight{p_end}
{p 25 30}{cmd:[rw]}   - indicates the set of replicate weights{p_end}
{p 25 30}{cmd:[all]}  - indicates both {cmd:[pw]} and {cmd:[rw]}{p_end}


{title:Description}

{p}{cmd:survwgt} creates sets of weights for replication-based variance estimation
techniques for survey data.  These include balanced repeated replication (BRR) and several
version of the survey jackknife (JK*).  These replication methods are alternates to the
Taylor series linearization methods used by
Stata's {help svy:svy-based} commands.

{p}In addition, {cmd:survwgt} performs poststratification,
raking, and non-response adjustments to survey weights.

{p 0}{cmd:survwgt create} creates a set of replicate weights for a dataset.  {cmd:survwgt} can
create four types of replicate weights, depending on the nature of the complex
sample design and user preferences.  In each method, multiple weight variables are created.  Each
set of replicate weights is calcuated by setting the sampling weights for observations
in one or more PSUs to zero, and adjusting the sampling weights for the remaining observations
to reproduce the full-sample
totals.  The {help svr} set of commands use these weights to calculate (co)variances
estimates of parameters by repeatedly estimating statistics of interest with each set of
replicate weights.  See Wolter (1985) for details.

{p 4 8}{cmd:brr} (balanced repeated replication) is appropriate for designs with
exactly two PSUs per stratum.  Technically, (CHECK) PSUs must have been selected
without replacement; any subsequent subsampling within PSUs is acceptable.
In BRR, {it:n} weights are created, in which {it:n} is the smallest multiple of four
greater than or equal to the number of strata.  In each set of weights,
one PSU from each stratum is included and the other excluded, in a
pattern defined by a Hadamard matrix.  Specifications for Hadamard matrices up to
dimension 512 are included with {cmd:survwgt}, which allows for designs with up to 512 strata.
Larger Hadamard matrices may be provided by the user, up to the limits of {help matsize}.{p_end}

{p 4 8}{cmd:jk1} (unstratified delete-one jackknife) is appropriate for non-stratified,
clustered sampling designs.  In JK1, one PSU is deleted from each set of replicate weights, so
the number of replicate weights equals the number of PSUs. {p_end}

{p 4 8}{cmd:jk2} (two per stratum delete-one jackknife) is appropriate for the same
designs as the balanced repeated replication method: two PSUs per stratum, selected with
replacement, with any subsampling scheme within PSU.  In the {cmd:jk2} method, one PSU is
deleted from each replicate (as opposed to one PSU {it:per stratum} in the {cmd:brr} method).{p_end}

{p 4 8}{cmd:jkn} (delete-n jackknife) is appropriate for sampling designs with two
or more PSUs per stratum.  [Insert description here!]{p_end}

{p 0}{cmd:survwgt poststratify} computes post-stratification adjustments to survey sampling
weights.  The sampling weights in each stratum are adjusted by a multiplicative factor such
that the sum of the weights equals the control total for each stratum, as specified
in the {cmd:totvar()} option.  When more than one sampling weight variable is specified,
the command post-stratifies each in turn.  This allows for the adjustment of the main
sampling weight and a full set of replicate weights in one easy step.

{p 0}{cmd:survwgt rake} computes raking adjustments to survey sampling
weights.  Raking is used when there are multiple stratification dimension, when control
totals known for the marginal distribution of each dimension but not for the individual
cell totals.  (When population cell totals are known, post-stratification should
be used.)  In raking, the sampling weights for each stratum are iteratively adjusted
by a multiplicative factor such
that the sum of the weights equals the control total for marginal dimension, in turn, until
convergence is achieved.  As with post-stratification, multiple sets of analysis and replicate
weights can be raked with one call to {cmd:survwgt}.

{p 0}{cmd:survwgt nonresponse} computes non-response adjustments to survey sampling
weights.  Nonresponse adjustment requires a dataset that includes the full sample--
responders and non-responders.  Separately within each response stratum, the base survey
sampling weight for each responder in the
sample is adjusted such that the total weight for responders alone equals the total weight
for the sample.  The weight for non-responders is set to zero.  As with the other
weight adjustment routines, multiple variables can be subjected to non-response adjustment in
one easy call to {cmd:survwgt}.


{title:Options for {cmd:survwgt create}}

{p 0 4}{cmdab:strata(}{it:varname}{cmd:)} specifies the variable that identifies stratum membership.
This must be a single variable; if the strata are defined by multiple variables, a single
variable can be created with {help egen}'s group() option.  The {cmd:strata()}
option is required for all
weight types except JK1, for which it is not allowed.

{p 0 4}{cmdab:psu(}{it:varname}{cmd:)} specifies the variable that identifies the primary sampling
units within strata.  It is required for all types of replicate weight creation.

{p 0 4}{cmdab:weight(}{it:varname}{cmd:)} specifies the base sampling weights.  It is required.

{p 0 4}{cmdab:stem)}{it:stem}{cmd:)} specifies a stem to be used as the basis for the replicate weight
variable names.  The repliciate weight variables are named stem1, stem2, ... stem{it:n}.  If
{cmd:stem()} is not specified, a stem based on the type of weights is used (brr_, jk1_, jk2_, or jkn_)

{p 0 4}{cmd:fay(}{it:#}{cmd:)} specifies the value of the constant to be used in generating weights
according to Fay's variant of balanced repeated replication.  In this method, observations in
the selected PSUs are assigned weight of (2-fay), and those in the non-selected PSUs are assigned
a weight of (fay), rather than 2 and 0, respectively.  By default, the Fay constant is 0, which
implies "regular" BRR.  This option is valid only for the brr method.

{p 0 4}{cmd:dof(}{it:#}{cmd:)} specifies the appropriate degrees of freedom for variance estimates.
By default, degrees of freedom is set to the number of strata for the BRR and JK2 methods, to one less
than the the number of PSUs for JK1, and to the total number of PSUs minus the total number of strata, for the
JKn method.

{p 0 4}{cmdab:hadmat(}{it:matname}{cmd:)} specifies a Stata system matrix that contains the Hadamard matrix
to create the replicates.  The program comes with a binary file with Hadamard matrices up to
dimension 512, so this option should be little-used.  No checking is done that the matrix is
in fact a Hadamard matrix -- be careful!

{p 0 4}{cmdab:hadfile(}{it:matrix_file_name}{cmd:)} specifies the system file that contains Hadamard
matrices.  This should only be necessary when the system file is located off the Stata search path,
or named something other than the default.

{p 0 4}{cmdab:nodots} specifies that a dot should not be displayed for each set of weights that
is created.  With large datasets, the dots can reassure you that the program has not died.


{title:Options for {cmd:survwgt poststratify}, {cmd:rake}, and {cmd:nonresponse}}

{p 0 4}{it:varspec} specifies the base weight(s) to adjusted (i.e., post-stratified, raked, or adjusted for
non-response).  This can be specified as a Stata {help varlist}.  More usefully, this can be specified as
{cmd:[pw]}, which indicates the currently specified main analysis weight, and/or {cmd:[rw]} which indicates
the set of replicate weights.  {cmd:[all]} is a synonym for {cmd:[pw] [rw]}.  If this automated
variable specification is used, then the svr settings for the dataset are updated to specify the
new weights, unless the {cmd:noupdate} option is specified.  See {help svrset}.

{p 0 4}{cmdab:noup:date} specifies that the svr settings for the dataset should not be updated to reflect
the adjusted weights.  This only has an effect when the variables to be adjusted are specified with
the "automatic" syntax discussed above.

{p 0 4}{cmdab:by(}{it:varlist}{cmd:)} specifies variable(s) identifying the strata.  For post-stratification,
the base weights are adjusted to sum to the control totals for the {it:cells} defined by the strata; for
raking, the base weights are adjusted to sum to the control totals for the {it:marginals} of the strata.
For non-response adjustment, the base weights for respondents are adjusted to sum to the total of the full
sample weights for the cells defined by the strata.

{p 0 4}{cmdab:totvar}[{cmd:s}]{cmd:(}{it:varname}[{it:s}]{cmd:)} specifies the variable[s] containing
control totals for post-stratification or raking.  For post-stratification, {cmd:totvar()}
must be a single variable, constant within the cells defined by the
{cmd:by(}{it:varlist}{cmd:)}, of control totals.  For raking, {cmd:totvars()} must contain
variables (one per variable specified {cmd:by()}), which specify the marginal control total for each
value of the corresponding stratum variable.  This option is not valid for non-response
adjustment.

{p 0 4}{cmdab:respvar(}{it:varname}{cmd:)} specifies the variable that contains response information
for members of the sample.  This variable must take on values of 0 (indicating non-response),
1 (indicating response), or missing (out of sample).  The base weights are adjusted such that,
within each response stratum, the adjusted weight for respondents sums to the total of the
base weight for all sample members.  Non-respondent cases are assigned an adjusted weight of zero, and
out of sample cases are excluded from the calculations and assigned missing for the adjusted weight.

{p 4 4}If there are no respondents in a stratum, all weights for that stratum are set to zero and a warning is
displayed.  If there are no sample members in a stratum, all weights are set to missing and a warning
is displayed.  This option is only valid for non-response adjustment.

{p 0 4}{cmdab:generate(}{it:varlist}{cmd:)} specifies the explicitly the names for the
adjusted weight variable(s)
to be created. There must be one name per base sampling weight specified in {it:varlist}.

{p 0 4}{cmdab:stem}{it:stem}{cmd:)} specifies a stem to be used to create names for the
adjusted weight variable(s).  New variables are numbered from 1, unless the "pw" or "all" are
indicated for the {it:varspec}, in which case they are numbered from 0.

{p 0 4}{cmdab:prefix}{it:prefix}{cmd:)} specifies a prefix to be prepended to the existing
variable names used to create the adjusted weight variable(s).

{p 0 4}{cmd:replace} specifies that the adjusted variables should replace the existing variables.
This option should be used with caution.

{p 0 4}{cmd:modify} specifies that the adjusted variables should replace the existing variables, 
{it:but only for observations specified by the if or in condition(s)}.  Without if() or in()
conditions, {cmd:modify} and {cmd:replace} have the same effect.  With an {cmd:if} and/or {cmd:in}
restriction, {cmd:replace} will replace all other observations as missing, while {cmd:modify} will 
leave them as-is.
This option should be used with extreme caution.


{title:Examples}



{title:Methods and formulae for weight calculation}

{p}{cmd:survwgt create} only works for survey designs that exactly match the specificatons
for the type of weights requested (two PSUs per stratum for BRR, etc.)  Any collapsing of strata or
PSUs, splitting of certainty PSUs, or other adjustments to approximate the appropriate
design must be done outside of the program.

{p}The program creates k sets of replicate weights, where k is defined as discussed above for
the replication method.

{p}For the {cmd:BRR} method, the
the program selects one of the PSUs from each stratum, according to a Hadamard matrix
of the relevant dimension. For replicate {it:j}, the weights for each observation {it: i} are
calculated as follows:


     W    = W   * (2-k)         for observations in the PSU
      {it:ij}     {it:i}F                 selected into the replicate


          = W   * (k)           for observations in the other PSU
             {it:i}F

where

     W     is the full-sample weight for observation {it:i}, and
           {it:i}F

     k     is the constant for Fay's method.  For standard BRR, k=0.


{p}The program comes with an auxiliary binary file, survwgt_hadamardmatrixfile.ado,
which contains Hadamard matrices up to dimension 512.  These matrices are stored in a compressed binary format
to save disk space; the available matrix sizes can be obtained by typing
{cmd:survwgt create brr sizes}.  (Note: the binary file is named with an "ado" file
extension in order that it be installed in the correct directory by Stata's {help net:net install} and
{help ssc:ssc install} commands.  The file is not, in fact, a Stata program, and will issue
an appropriate error message if it is attempted to be run.)

{p}For the {cmd:JK1} method, the program creates one replicate per PSU.  In replicate {it:j}, the weights
for each observation {it:i} are calculated as follows:


     W    = 0                   for observations in PSU
      {it:ij}                                               {it:j}


          = W   * ( N/(N-1) )   for observations in other PSUs
             {it:i}F

where N is the number of PSUs, and W is defined as above.

{p}For the {cmd:JK2} method, the program creates one replicate per stratum.  In each replicate, the weights in the
selected stratum are doubled in the first PSU, and set to zero in the second PSU.  Weights in other strata
are not changed.

{p}For the {cmd:JKn} method, the program creates one replicate for PSU.  In each
replicate, the weights for each observation {it:i} are calculated as follows:

     W    = 0                   for observations in PSU  (from stratum {it:k})
      {it:ij}                                               {it:j}


          = W   * (N /(N -1))   for observations from other PSUs
             {it:i}F     {it:k}   {it:k}       in stratum {it:k}


          = W                   for observations in other strata
             {it:i}F

where

     N     is the number of PSUs in stratum {it:k}
      {it:k}



{title:Methods and formulae for variance estimation}

{p}The {cmd:svr} set of commands make use of the replication weights produced by {cmd:survwgt create}
to estimate (co)variances for parameters and other estimated quantities.  See {help svr} for a
list of these commands.  In general, the parameter
estimates are calculated by standard statistical commands using {help weight:aweights}, which
yields the same point estimates as Stata's linearization-based {help svy} commands for survey
data.  The (co)variances are calculated by repeatedly re-estimating the same parameters with
each of the set of replicate weights.  From these replicated estimates, the (co)variances are
calcuated as follows:


                 R
     V(b) = F * Sum( f *(b -b)(b -b)' )
                r=1   {it:r}   {it:r}     {it:r}

where

     R     is the number of replicates,

     b     is the vector of full sample point estimate(s),

     b     is the vector of estimates derived from replicate {it:r},
      {it:r}

     F     is a constant factor depending on the replication method, and

     f     is a replicate-specific factor.
      {it:r}


The values for F and f are:

     {cmd:method}      {cmd:F}           {cmd:f}

       BRR                 1/R          1

       Fay's variant  1/(R*(1-k)^2)     1
       of BRR

       JK1               (R-1)/R        1

       JK2                  1           1

       JKn                  1       (N -1)/N
                                      {it:k}     {it:k}



{title:Saved Results}

{p}The command saves no results, but it does set data {help char:characteristics} to
identify the full sample and replicate weight variables, degrees of freedom, fay constant for
BRR method, and replication method (BRR, JK1, JK2, or JKn).  The {help svrset} command
can be used to set, clear, or display these characteristics.


{title:References}

{p}Judkins, D. 1990.  Fay's Method for Variance Estimation.  Journal of Official
Statistics 16:25-45.

{p}Wolter, K. M. 1985. Introduction to Variance Estimation. New York: Springer-Verlag.


{title:Acknowledgements}

{p}I would like to thank Bobby Gutierrez at StataCorp for advice on implementation of BRR, and
the technical group at StataCorp for feedback on an early version of the BRR programs.  The code
for raking is partly based upon Nick Cox's program {help mstdize}.


{title:Author}

	Nicholas J. G. Winter
	University of Virginia
	nwinter@virginia.edu
